<!doctype html>
<html class="default no-js">
<head>
	<meta charset="utf-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<title>@aws/dynamodb-auto-marshaller</title>
	<meta name="description" content="">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<link rel="stylesheet" href="assets/css/main.css">
</head>
<body>
<header>
	<div class="tsd-page-toolbar">
		<div class="container">
			<div class="table-wrap">
				<div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base=".">
					<div class="field">
						<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
						<input id="tsd-search-field" type="text" />
					</div>
					<ul class="results">
						<li class="state loading">Preparing search index...</li>
						<li class="state failure">The search index is not available</li>
					</ul>
					<a href="index.html" class="title">@aws/dynamodb-auto-marshaller</a>
				</div>
				<div class="table-cell" id="tsd-widgets">
					<div id="tsd-filter">
						<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
						<div class="tsd-filter-group">
							<div class="tsd-select" id="tsd-filter-visibility">
								<span class="tsd-select-label">All</span>
								<ul class="tsd-select-list">
									<li data-value="public">Public</li>
									<li data-value="protected">Public/Protected</li>
									<li data-value="private" class="selected">All</li>
								</ul>
							</div>
							<input type="checkbox" id="tsd-filter-inherited" checked />
							<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
							<input type="checkbox" id="tsd-filter-externals" checked />
							<label class="tsd-widget" for="tsd-filter-externals">Externals</label>
						</div>
					</div>
					<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
				</div>
			</div>
		</div>
	</div>
	<div class="tsd-page-title">
		<div class="container">
			<ul class="tsd-breadcrumb">
				<li>
					<a href="globals.html">Globals</a>
				</li>
			</ul>
			<h1> @aws/dynamodb-auto-marshaller</h1>
		</div>
	</div>
</header>
<div class="container container-main">
	<div class="row">
		<div class="col-8 col-content">
			<div class="tsd-panel tsd-typography">
				<h1 id="amazon-dynamodb-automarshaller">Amazon DynamoDB Automarshaller</h1>
				<p><a href="http://aws.amazon.com/apache-2-0/"><img src="https://img.shields.io/github/license/awslabs/dynamodb-data-mapper-js.svg?style=flat" alt="Apache 2 License"></a></p>
				<p>This library provides a <code>Marshaller</code> class that converts native JavaScript
					values to DynamoDB AttributeValues and back again. It&#39;s designed to work with
					ES6 features like sets, maps, and iterables, and can be configured to support
					data types only supported by JavaScript (such as empty binary buffers) or by
				Amazon DynamoDB (such as numbers of arbitrary size) with minimal tradeoffs.</p>
				<h2 id="getting-started">Getting started</h2>
				<p>To use the <code>Marshaller</code> to convert a JavaScript object to the data type expected
					by Amazon DynamoDB, simply create an instance of the marshaller and call
				<code>marshallItem</code>:</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">import</span> {BinarySet, Marshaller} <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-auto-marshaller'</span>;

<span class="hljs-keyword">const</span> marshaller = <span class="hljs-keyword">new</span> Marshaller();
<span class="hljs-keyword">const</span> original = {
    <span class="hljs-built_in">string</span>: <span class="hljs-string">'a string'</span>,
    <span class="hljs-built_in">number</span>: <span class="hljs-number">1234</span>,
    list: [
        <span class="hljs-string">'a'</span>,
        <span class="hljs-string">'list'</span>,
        <span class="hljs-string">'of'</span>,
        <span class="hljs-string">'values'</span>,
    ],
    buffer: Buffer.from([<span class="hljs-number">0xde</span>, <span class="hljs-number">0xad</span>, <span class="hljs-number">0xbe</span>, <span class="hljs-number">0xef</span>]),
    setOfBuffers: <span class="hljs-keyword">new</span> BinarySet([
        <span class="hljs-built_in">Uint8Array</span>.from([<span class="hljs-number">0xde</span>, <span class="hljs-number">0xad</span>]),
        <span class="hljs-built_in">Uint8Array</span>.from([<span class="hljs-number">0xbe</span>, <span class="hljs-number">0xef</span>]),
        <span class="hljs-built_in">Uint8Array</span>.from([<span class="hljs-number">0xfa</span>, <span class="hljs-number">0xce</span>]),
    ] <span class="hljs-keyword">as</span> Iterable&lt;ArrayBufferView&gt;),
    stringSet: <span class="hljs-keyword">new</span> Set&lt;<span class="hljs-built_in">string</span>&gt;([
        <span class="hljs-string">'foo'</span>,
        <span class="hljs-string">'bar'</span>,
        <span class="hljs-string">'baz'</span>,
    ]),
    <span class="hljs-built_in">any</span>: {
        level: {
            of: {
                nesting: {
                    is: {
                        supported: <span class="hljs-literal">true</span>
                    }
                }
            }
        }
    },
}

<span class="hljs-comment">// create a variable ready to be used with DynamoDB's low-level API </span>
<span class="hljs-keyword">const</span> marshalled = marshaller.marshallItem(original);

<span class="hljs-comment">// the output of `.marshallItem` can be converted back to a JavaScript type with</span>
<span class="hljs-comment">// `.unmarshallItem`</span>
<span class="hljs-keyword">const</span> unmarshalled = marshaller.unmarshallItem(original);

<span class="hljs-comment">// With a few caveats (listed below), the unmarshalled value should have the</span>
<span class="hljs-comment">// same structure and data as the original value.</span>
deepEqual(original, unmarshalled); <span class="hljs-comment">// true</span>
</code></pre>
				<p>Values may be converted to and from AttributeValue objects with <code>.marshallValue</code>
				and <code>.unmarshallValue</code> directly:</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">import</span> {Marshaller} <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-auto-marshaller'</span>;

<span class="hljs-keyword">const</span> marshaller = <span class="hljs-keyword">new</span> Marshaller();
<span class="hljs-keyword">const</span> marshalled = marshaller.marshallValue(<span class="hljs-string">'string'</span>); <span class="hljs-comment">// returns {S: 'string'}</span>
<span class="hljs-keyword">const</span> unmarshalled = marshaller.unmarshallValue(marshalled); <span class="hljs-comment">// returns 'string'</span>
</code></pre>
				<h2 id="caveats">Caveats</h2>
				<p>There are a few categories of values that cannot be seamlessly converted between
				JavaScript and DynamoDB, such as big numbers, empty values, and mixed-type sets.</p>
				<h3 id="big-number-support">Big number support</h3>
				<p>By default, the marshaller will unmarshall numeric values returned by DynamoDB
					into instances of <code>NumberValue</code> rather than into native JavaScript numbers.
					Numbers in DynamoDB may have up to 38 digits of precision, which exceeds the
					precision available in a JavaScript <code>number</code>. <code>NumberValue</code> instances therefore
					store the value returned by DynamoDB as a string and will only coerce the value
					into a JavaScript number when the instance appears in an arithmetic expression,
				when it is passed to <code>JSON.stringify</code>, or when its <code>valueOf</code> method is called.</p>
				<p>Similarly, numeric sets are returned as <code>NumberValueSet</code> instances that are
				compatible with both numbers and <code>NumberValue</code>s.</p>
				<p>To disable this behavior, pass a configuration options argument to the
				<code>Marshaller</code> constructor with <code>unwrapNumbers</code> set to <code>true</code>:</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">import</span> {Marshaller} <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-auto-marshaller'</span>;

<span class="hljs-keyword">const</span> marshaller = <span class="hljs-keyword">new</span> Marshaller({unwrapNumbers: <span class="hljs-literal">true</span>});
</code></pre>
				<h3 id="empty-value-support">Empty value support</h3>
				<p>DynamoDB&#39;s data model requires that strings, sets, and binary attributes have
					lengths greater than zero, whereas JavaScript has no such requirement. By
					default, the marshaller will not attempt to alter empty values, as the
					marshaller would not be able to disambiguate any sigil value used from a field
				that was meant to legitimately contain that value.</p>
				<p>The marshaller offers two opt-in options for handling empty values, both of
				which are controlled using the <code>onEmpty</code> configuration option.</p>
				<p>Settting <code>onEmpty</code> to <code>&#39;nullify&#39;</code> will direct the marshaller to convert empty
					values to null attribute values (<code>{NULL: true}</code>) and persist them to DynamoDB.
					This allows consumers of the item to know that an empty value was saved, though
					it will be slightly altered. When fetched from DynamoDB, the value will be
				unmarshalled as <code>null</code>:</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">import</span> {Marshaller} <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-auto-marshaller'</span>;

<span class="hljs-keyword">const</span> marshaller = <span class="hljs-keyword">new</span> Marshaller({onEmpty: <span class="hljs-string">'nullify'</span>});
<span class="hljs-keyword">const</span> marshalled = marshaller.marshallValue(<span class="hljs-string">''</span>); <span class="hljs-comment">// returns {NULL: true}</span>
<span class="hljs-keyword">const</span> unmarshalled = marshaller.unmarshallValue(marshalled); <span class="hljs-comment">// returns null</span>
</code></pre>
				<p>Setting <code>onEmpty</code> to <code>&#39;omit&#39;</code> will direct the marshaller to remove empty values
				from the serialized item:</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">import</span> {Marshaller} <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-auto-marshaller'</span>;

<span class="hljs-keyword">const</span> marshaller = <span class="hljs-keyword">new</span> Marshaller({onEmpty: <span class="hljs-string">'omit'</span>});
<span class="hljs-keyword">const</span> marshalled = marshaller.marshallValue(<span class="hljs-string">''</span>); <span class="hljs-comment">// returns undefined</span>
<span class="hljs-keyword">const</span> unmarshalled = marshaller.unmarshallValue(marshalled); <span class="hljs-comment">// returns undefined</span>
</code></pre>
				<h3 id="symbols-and-functions">Symbols and functions</h3>
				<p>By default, the marshaller will throw an error when it encounters a symbol or
					function. You can direct the marshaller to instead omit such values from its
				output by setting the <code>onInvalid</code> configuration option to <code>&#39;omit&#39;</code>:</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">import</span> {Marshaller} <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-auto-marshaller'</span>;

<span class="hljs-keyword">const</span> marshaller = <span class="hljs-keyword">new</span> Marshaller({onInvalid: <span class="hljs-string">'omit'</span>});
<span class="hljs-keyword">const</span> marshalled = marshaller.marshallValue(Symbol.iterator); <span class="hljs-comment">// returns undefined</span>
<span class="hljs-keyword">const</span> unmarshalled = marshaller.unmarshallValue(marshalled); <span class="hljs-comment">// returns undefined</span>
</code></pre>
			</div>
		</div>
		<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
			<nav class="tsd-navigation primary">
				<ul>
					<li class="globals  ">
						<a href="globals.html"><em>Globals</em></a>
					</li>
				</ul>
			</nav>
			<nav class="tsd-navigation secondary menu-sticky">
				<ul class="before-current">
					<li class=" tsd-kind-class">
						<a href="classes/binaryset.html" class="tsd-kind-icon">Binary<wbr>Set</a>
					</li>
					<li class=" tsd-kind-class">
						<a href="classes/marshaller.html" class="tsd-kind-icon">Marshaller</a>
					</li>
					<li class=" tsd-kind-class">
						<a href="classes/numbervalue.html" class="tsd-kind-icon">Number<wbr>Value</a>
					</li>
					<li class=" tsd-kind-class">
						<a href="classes/numbervalueset.html" class="tsd-kind-icon">Number<wbr>Value<wbr>Set</a>
					</li>
					<li class=" tsd-kind-class tsd-has-type-parameter">
						<a href="classes/objectset.html" class="tsd-kind-icon">Object<wbr>Set</a>
					</li>
					<li class=" tsd-kind-interface">
						<a href="interfaces/marshallingoptions.html" class="tsd-kind-icon">Marshalling<wbr>Options</a>
					</li>
					<li class=" tsd-kind-interface">
						<a href="interfaces/unmarshalledlistattributevalue.html" class="tsd-kind-icon">Unmarshalled<wbr>List<wbr>Attribute<wbr>Value</a>
					</li>
					<li class=" tsd-kind-interface">
						<a href="interfaces/unmarshalledmapattributevalue.html" class="tsd-kind-icon">Unmarshalled<wbr>Map<wbr>Attribute<wbr>Value</a>
					</li>
					<li class=" tsd-kind-type-alias">
						<a href="globals.html#binaryvalue" class="tsd-kind-icon">Binary<wbr>Value</a>
					</li>
					<li class=" tsd-kind-type-alias">
						<a href="globals.html#emptyhandlingstrategy" class="tsd-kind-icon">Empty<wbr>Handling<wbr>Strategy</a>
					</li>
					<li class=" tsd-kind-type-alias">
						<a href="globals.html#invalidhandlingstrategy" class="tsd-kind-icon">Invalid<wbr>Handling<wbr>Strategy</a>
					</li>
					<li class=" tsd-kind-type-alias">
						<a href="globals.html#unmarshalledattributevalue" class="tsd-kind-icon">Unmarshalled<wbr>Attribute<wbr>Value</a>
					</li>
					<li class=" tsd-kind-function">
						<a href="globals.html#isarraybuffer" class="tsd-kind-icon">is<wbr>Array<wbr>Buffer</a>
					</li>
					<li class=" tsd-kind-object-literal">
						<a href="globals.html#emptyhandlingstrategies" class="tsd-kind-icon">Empty<wbr>Handling<wbr>Strategies</a>
					</li>
					<li class=" tsd-kind-object-literal">
						<a href="globals.html#invalidhandlingstrategies" class="tsd-kind-icon">Invalid<wbr>Handling<wbr>Strategies</a>
					</li>
				</ul>
			</nav>
		</div>
	</div>
</div>
<footer>
	<div class="container">
		<h2>Legend</h2>
		<div class="tsd-legend-group">
			<ul class="tsd-legend">
				<li class="tsd-kind-module"><span class="tsd-kind-icon">Module</span></li>
				<li class="tsd-kind-object-literal"><span class="tsd-kind-icon">Object literal</span></li>
				<li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li>
				<li class="tsd-kind-function"><span class="tsd-kind-icon">Function</span></li>
				<li class="tsd-kind-function tsd-has-type-parameter"><span class="tsd-kind-icon">Function with type parameter</span></li>
				<li class="tsd-kind-index-signature"><span class="tsd-kind-icon">Index signature</span></li>
				<li class="tsd-kind-type-alias"><span class="tsd-kind-icon">Type alias</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-enum"><span class="tsd-kind-icon">Enumeration</span></li>
				<li class="tsd-kind-enum-member"><span class="tsd-kind-icon">Enumeration member</span></li>
				<li class="tsd-kind-property tsd-parent-kind-enum"><span class="tsd-kind-icon">Property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-enum"><span class="tsd-kind-icon">Method</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li>
				<li class="tsd-kind-interface tsd-has-type-parameter"><span class="tsd-kind-icon">Interface with type parameter</span></li>
				<li class="tsd-kind-constructor tsd-parent-kind-interface"><span class="tsd-kind-icon">Constructor</span></li>
				<li class="tsd-kind-property tsd-parent-kind-interface"><span class="tsd-kind-icon">Property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-interface"><span class="tsd-kind-icon">Method</span></li>
				<li class="tsd-kind-index-signature tsd-parent-kind-interface"><span class="tsd-kind-icon">Index signature</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-class"><span class="tsd-kind-icon">Class</span></li>
				<li class="tsd-kind-class tsd-has-type-parameter"><span class="tsd-kind-icon">Class with type parameter</span></li>
				<li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li>
				<li class="tsd-kind-property tsd-parent-kind-class"><span class="tsd-kind-icon">Property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class"><span class="tsd-kind-icon">Accessor</span></li>
				<li class="tsd-kind-index-signature tsd-parent-kind-class"><span class="tsd-kind-icon">Index signature</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited constructor</span></li>
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited accessor</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected accessor</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private accessor</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static property</span></li>
				<li class="tsd-kind-call-signature tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static method</span></li>
			</ul>
		</div>
	</div>
</footer>
<div class="overlay"></div>
<script src="assets/js/main.js"></script>
<script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script>
</body>
</html>